---
id: popover
title: Popover
description: An overlay that displays additional information or options when triggered.
---

<ComponentPreview id="Popover" />

## Anatomy

To set up the popover correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="popover" />

## Examples

Learn how to use the `Popover` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Using a Portal

By default, the popover is rendered in the same DOM hierarchy as the trigger. To render the popover within a portal, set
the `portalled` prop to `true`.

> Note: This requires that you render the component within a `Portal` based on the framework you use.

<Example id="portalled" />

### Adding an arrow

To render an arrow within the popover, render the component `Popover.Arrow` and `Popover.ArrowTip` as children of
`Popover.Positioner`.

<Example id="arrow" />

### Listening for open and close events

When the popover is opened or closed, we invoke the `onOpenChange` callback.

<Example id="on-open-change" />

### Control the open state

Use the `isOpen` prop to control the open state of the popover.

<Example id="controlled" />

### Modifying the close behavior

The popover is designed to close on blur and when the <kbd>esc</kbd> key is pressed.

To prevent it from closing on blur (clicking or focusing outside), pass the `closeOnInteractOutside` prop and set it to
`false`.

To prevent it from closing when the <kbd>esc</kbd> key is pressed, pass the `closeOnEsc` prop and set it to `false`.

<Example id="close-behavior" />

### Changing the placement

To change the placement of the popover, set the `positioning` prop.

<Example id="positioning" />

### Changing the modality

In some cases, you might want the popover to be modal. This means that it'll:

- trap focus within its content
- block scrolling on the body
- disable pointer interactions outside the popover
- hide content behind the popover from screen readers

To make the popover modal, set the `modal` prop to `true`. When `modal={true}`, we set the `portalled` attribute to
`true` as well.

<Example id="modal" />

### Using the Root Provider

The `RootProvider` component provides a context for the popover. It accepts the value of the `usePopover` hook. You can
leverage it to access the component state and methods from outside the popover.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## Guides

### Available height and width

The following css variables are exposed to the `Popover.Positioner` which you can use to style the `Popover.Content`

```css
/* width of the popover trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, use the following css:

```css
[data-scope='popover'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

<ComponentTypes id="popover" />

### Context

These are the properties available when using `Popover.Context`, `usePopoverContext` hook or `usePopover` hook.

<ContextType id="popover" />

## Accessibility

### Keyboard Support

<KeyBindingsTable id="popover" />
